Queues support several operations, as listed in Table 1.
Table 1. Queue Operations
Operation | Description |
---|
Create Queue | Creates a new queue under the given account. You can specify metadata for the queue during creation. |
Delete Queue | Marks
the specified queue for deletion. The garbage collector deletes marked
queues on a periodic basis. So, if you delete a queue and try to create
it immediately, the Queue service complains that the queue already
exists. |
Get Queue Metadata | Gets the user-defined queue metadata and other queue properties. The metadata is retrieved in the form of name-value pairs. |
Set Queue Metadata | Sets
the metadata values of the specified queue. Set Queue Metadata replaces
all the metadata of the specified queue with new values. |
Table 2 lists some of the important characteristics of the queue operations listed in Table 1.
Table 2 lists the HTTP verb, cloud URI, development storage URI, HTTP version, and access control for the queues. The <account name> is the storage account name in the cloud, and the <devstorageaccount>
is the development storage account. Observe that unlike blob
containers, all the operations can be called only with the account
owner privileges.
The following sections discuss some of the operations from Table 5-7
in detail. Even though the operations are different, the programming
concepts behind them are similar. To keep the book at a conceptual
level, I discuss just the Create Queue and Set Queue Metadata
operations. By studying these operations in detail, you can understand
the programming concepts behind all the queue operations. The Windows
Azure Storage Operations application included with this chapter's
source code contains an implementation of all the queue operations.
1. Create Queue
The Create Queue operation creates a queue in a storage account. The URI for the Create Queue operation is of the format account name>.queue.core.windows.net/<queue name>.
You can think of Queue as a message queuing system in the cloud. For
example, if you want to send and receive messages across diverse
applications in different domains, Windows Azure Queue may fit your
requirement. Because of its standard REST interface and Internet scale,
you can send and receive queue messages anywhere, anytime, and in any
programming language that supports Internet programming. The Create
Queue REST request looks like Listing 5-8.
Example 1. Create Queue REST Request
PUT /myfirstazurequeue?timeout=30 HTTP/1.1 x-ms-date: Wed, 17 Jun 2009 03:16:12 GMT Authorization: SharedKey proazurestorage:a0EQSlfMdXfFrP/wwdfCUVqMYiv4PjXesF0Jp4d71DA= Host: proazurestorage.queue.core.windows.net Content-Length: 0
|
Listing 1
shows the request for creating a queue named myfirstazurequeue. The PUT
HTTP verb instructs the Queue service to create a queue. There is no
metadata information for the queue, so the queue is created without any
metadata. You can add x-ms-meta-[name]:[value] to the header to create
metadata values. For the Create Queue operation, the Queue service
responds with a status code of HTTP/1.1 201 Created, or HTTP/1.1 409
Conflict if a queue with the same name already exists. The Create Queue
response is shown in Listing 2.
Example 2. Create Queue REST Response
HTTP/1.1 201 Created Server: Queue Service Version 1.0 Microsoft-HTTPAPI/2.0 x-ms-request-id: 8b4d45c8-2b5d-46b8-8e14-90b0d902db80 Date: Wed, 17 Jun 2009 03:17:57 GMT Content-Length: 0
|
In Listing 2,
the first line represents the status code of the operation. The
x-ms-request-id represents a unique request identifier that can be used
for debugging or tracing.
Figure 1 shows the working of the Create Queue operation in the Windows Azure Storage Operations application.
As shown in Figure 5-8, to create a queue, you need to do the following:
Go to the Queue Operations tab.
Enter a queue name (such as myfirstazurequeue) in the Queue Name text field.
Select the Create Queue operation from the Operations list box.
Click
the Execute button. After the queue is created, the queues list box in
the Account section is refreshed with the newly created queue name in
it.
The WindowsAzureStorageHelper class in the
ProAzureCommonLib contains a helper function called CreateQueue, as
shown in Listing 3.
Example 3. Create Queue Method in the WindowsAzureStorageHelper Class
public bool CreateQueue(string queueName, out bool alreadyExists) { alreadyExists = false; MessageQueue q = QueueStorageType.GetQueue(queueName);
return q.CreateQueue(out alreadyExists); }
|
As shown in Listing 3,
the CreateQueue() method calls the GetQueue() method to get a reference
to the MessageQueue object. The MessageQueue object is a local instance
of the Queue object. This instance doesn't create a queue when you
instantiate it. To create a queue, you have to call the CreateQueue()
method on the MessageQueue object. The MessageQueue object is used by
the StorageClient to create accurate URI and metadata headers and send
them to the Queue service. Figure 2 illustrates the sequence of method calls across different objects and assemblies for the Create Queue operation.
As shown in Figure 2,
the Windows Azure Storage Operations application calls the
CreateQueue() method on the WindowsStorageHelper object in the
ProAzureCommonLib.dll. The WindowsStorageHelper object calls the
GetQueue() method on the QueueStorage object to get an instance of the
MessageQueue object. The WindowsStorageHelper object then calls the
CreateQueue() method on the MessageQueue object. The CreateQueue()
method creates the REST message and sends it synchronously to the
Windows Azure Queue service to create the queue. It uses the
System.Net.HttpWebRequest to send the REST message over HTTP. Upon
success or failure of the operation, the Windows Azure Queue service
returns an HTTP status code: HTTP/1.1 201 for success or HTTP/1.1 409
for conflict or failure. The CreateQueue() method translates the HTTP
status code into true for success and false for failure or conflict.
The Boolean value is passed all the way to the Windows Azure Storage
Operations application as a return parameter of the CreateQueue()
method.
2. Set Queue Metadata
Queues can contain name-value
pairs of metadata values. You can store values like the time of
creation, creator, last modified by user, and so on in the metadata
fields of a container. The size of the metadata can be 8KB per queue.
The Set Queue Metadata operation sets the metadata of a queue
independently. The URI for the Set Queue Metadata operation is of the
format account name>.queue.core.windows.net/<queue name>?comp=metadata. The Set Queue Metadata REST request looks like Listing 4.
Example 4. Set Queue Metadata REST Request
PUT /myfirstazurequeue?comp=metadata&timeout=30 HTTP/1.1 x-ms-date: Wed, 17 Jun 2009 04:33:45 GMT x-ms-meta-createdBy: tejaswi x-ms-meta-creationDate: 6/16/2009 Authorization: SharedKey proazurestorage:spPPnadPYnH6AJguuYT9wP1GLXmCjn0I1S6W2+hzyMc= Host: proazurestorage.queue.core.windows.net Content-Length: 0
|
In Listing 5,
the HTTP verb used is PUT, and the URI parameter is ?comp=metadata.
This parameter instructs the Queue service to set the queue metadata
instead of creating the queue. The Create Queue operation doesn't have
this parameter. The x-ms-meta.[name]:[value] entries represent the
metadata name-value pairs you want to set on the queue.
Set Queue Metadata
operation replaces all the existing metadata of the queue. It doesn't
update individual metadata entries. For example, if a queue has two
metadata values Creator and Creation-Time, and you call Set Queue
Metadata with only one metadata value LastUpdatedBy, then the Creator
and Creation-Time values will be deleted and the queue will have only
one metadata value: LastUpdatedBy. To avoid this side effect, always
set all the metadata values again along with any new values you want to
add to the queue's metadata.
|
|
Figure 3 illustrates how to execute the Set Queue Metadata operation in Windows Azure Storage Operations application.
As shown in Figure 3, to execute the Set Queue Metadata operation, you do the following:
Go to the Queue Operations tab.
In the Account section, click the List Queues button to get a list of queues in your account.
Select one of the queues from the list (such as myfirstazurequeue).
Make sure the Queue Name text box in the Queues section displays the name of the selected queue.
In the Queues section, select the Set Queue Metadata operation from list of queue operations.
In the Queues section, enter metadata name-value pairs in the Metadata section.
Click the Execute button to execute the operation.
To
verify the success of the operation, click the Clear Results button in
the Queues section, and re-select the queue from the Queues list in the
Account section to retrieve the newly set metadata values.
The WindowsAzureStorageHelper class in the
ProAzureCommonLib contains a helper function called
SetQueueProperties(), as shown in Listing 5.
Example 5. SetQueueProperties Method in the WindowsAzureStorageHelper Class
public bool SetQueueProperties(string queueName, QueueProperties queueProps) { MessageQueue q = QueueStorageType.GetQueue(queueName);
return q.SetProperties(queueProps); }
|
In Listing 5,
the SetQueueProperties() method accepts the name of the queue and a
QueueProperties object populated with metadata name-value pairs. The
QueueProperties class has a property Metadata of type
System.Collections.Specialized.NameValueCollection, which represents
the metadata name-value pairs. The queue name is used to create a local
instance of the MessageQueue object. The code then calls the
SetProperties() method on the MessageQueue object to set the metadata
values for the queue. If the metadata is set successfully, a Boolean
value of true is returned back to the caller; otherwise, a false value
is returned. Figure 4 illustrates the sequence of method calls across different objects and assemblies for the Set Queue Metadata operation.
As shown in Figure 4,
the Windows Azure Storage Operations application calls the
SetQueueProperties() method on the WindowsStorageHelper object in the
ProAzureCommonLib.dll. The WindowsStorageHelper object calls the
GetQueue() method on the QueueStorage object to get an instance of the
MessageQueue object. The WindowsStorageHelper object then calls the
SetProperties() method on the MessageQueue object. The SetProperties()
method creates the REST message and sends it synchronously to the
Windows Azure Queue service to set the queue metadata values. It uses
the System.Net.HttpWebRequest to send the REST message over HTTP. Upon
success or failure of the operation, the Windows Azure Queue service
returns an HTTP status code: HTTP/1.1 200 for success or HTTP/1.1 204
(No content). The SetProperties() method translates the HTTP status
code into true for success and false for failure. The Boolean value is
passed all the way to the Windows Azure Storage Operations application
as a return parameter of the SetQueueProperties() method.